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CN MESA (Modules for Experiments in Stellar Astrophysics) has become very 

, , popular among astrophysicists as a powerful and reliable code to simulate 

stellar evolution. Analyzing the output data thoroughly may, however, present 

some challenges and be rather time-consuming. 

43 Here we describe MESAFace, a graphical and dynamical interface which 

^ provides an intuitive, efficient and quick way to analyze the MESA output. 
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Nature of problem: 

Find a way to quickly and thoroughly analyze the output of a MESA run, including 
all the profiles, and have an efficient method to produce graphical representations 
of the data. 
Solution method: 

We created two scripts (to be run consecutively). The first one downloads all the 
data from a MESA run and organizes the profiles in order of age. All the files 
are saved as tables or arrays of tables which can then be accessed very quickly by 
Mathematica. The second script uses the Manipulate function to create a graphi- 
cal interface which allows the user to choose what to plot from a set of menus and 
buttons. The information shown is updated in real time. The user can access very 
quickly all the data from the run under examination and visualize it with plots 
and tables. 
Unusual features: 

Moving the slides in certain regions may cause an error message. This happens 
when Mathematica is asked to read nonexistent data. The error message, however, 
disappears when the slides are moved back. This issue does not preclude the good 
functioning of the interface. 
Additional comments: 

The program uses the dynamical capabilities of Mathematica. When the program 
is opened, Mathematica prompts the user to " Enable Dynamics" . It is necessary 
to accept before proceeding. 
Running time: 

Depends on the size of the data downloaded, on where the data are stored (hard- 
drive or web), and on the speed of the computer or network connection. In general, 
downloading the data may take from a minute to several minutes. Loading directly 
from the web is slower. For example, downloading a 200MB data folder (a total of 
102 files) with a dual-core Intel laptop, P8700, 2 GB of RAM, at 2.53 GHz took 
about a minute from the hard-drive and about 23 minutes from the web (with a 
basic home wireless connection). 



1. Introduction 

The introduction of the new code for stellar evolution, MESA [lj (Modules 
for Experiments in Stellar Astrophysics) represented somewhat of a revolu- 
tion in the field of computational stellar evolution. 

MESA is a one-dimensional stellar evolution code, organized in indepen- 
dent modules and continually updated. The code can evolve stars with a 
very wide range of initial masses and metallicities; it allows the specification 
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of many parameters, for example, convection mechanism, mass loss, etc., and 
it can overcome difficulties typical of the previous stellar evolutionary codes. 
Notably, it can run a low mass star through the He-flash region. 

All these aspects and the fact that the code is publicly available [2] has 
made MESA extremely popular among astrophysicists and other physicists 
interested in stellar evolution and in how stars respond to new models of 
particle interactions. 

Being publicly available, MESA is widely accessible and is continually 
tested by hundreds of scientists and students all over the world. In addition, 
several researchers have created new codes and routines to improve it and to 
simplify its use [3]. 

A MESA run produces a very large amount of data on the life and struc- 
ture of the star. This information is saved in several files: the file "star. log" 
includes global information about the star at different times whereas a large 
number of profiles (named "logn.data", where n is an integer), contain de- 
tailed information about the profile of the star, each file referring to a specific 
age. 

Though it is relatively easy, and for some purposes sufficient, to analyze 
the file "star. log", a complete analysis of the MESA output, which includes 
in some cases hundreds of profiles, is much more challenging. In particular, 
to analyze the detailed structure of a star at a certain age, one should select 
the corresponding profile by reading the age of each of them (the information 
is provided in the 3 nd row of "logn.data"). Alternatively, one should read the 
model number corresponding to a certain age in the first column of the file 
"star. log", and then look for the log number associated with that age in the 
file "profile. index". Both ways are long and, in general, not very practical. 

Another common problem is reading the age of a star from its position in 
the HR diagram (or any other plot which does not show the age explicitly, 
e.g., the central temperature- central density diagram). It would be useful to 
have a quick access to that information and, at the same time, to know which 
of the many profiles describes the structure of the star at that age. 

Here we describe a graphical interface, MESAFace, which we created to 
address problems like the ones described above and, in general, to provide 
fast and simple access to all the information contained in the output of a 
MESA run, including all the profiles. 

MESAFace is a very intuitive, efficient, and easy-to-use dynamical in- 
terface, which allows the selection of the information to be shown through 
buttons and menus and the age of the star to be selected through a slidebar. 
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The code is written in Mathematica and has been tested with Mathemat- 
ica 7 and 8. However, a knowledge of Mathematica is not strictly necessary 
to use the interface. 

MESAFace needs to access the MESA output data which, in a standard 
MESA run, are saved in the folder /work/LOGS. The data can also be down- 
loaded directly from the web. Possibly soon, the results from some standard 
runs will be available from a dedicated web space. 

After the data has been loaded, MESAFace presents a graphical interface 
structured in three vertically organized panels: 

• A history plot panel; 

• A profile plot panel; 

• An information panel. 

All the controls (buttons, menus, check-boxes, etc.) are contained on the left 
side of the interface. The user can decide what to plot and can change the 
age of the star by using these controls while the information shown on the 
right side is dynamically updated. Several aspects of the panels and graphs, 
for example, the color and style of the lines, can be customized by the user. 
A separate user manual [I] explains in detail how to do that. 

In this paper, we describe in detail the structure of the MESAFace code 
and how it accesses, manipulates, and presents the data. 

The structure of the paper is the following: We begin with a brief sum- 
mary of the MESA output, in section [2} Later, in section [3j we give a basic 
description of the general structure of the MESAFace code. In section |4j we 
describe with more details how MESAFace loads and organizes the files. In 
section [5j we discuss how it creates the dynamical interface and visualizes 
the data. Finally, in section [6] we conclude with some overall comments. 

A note on the style. We will use the Typewriter style for the content of 
the Mathematica notebook, "quotes" for the name of the MESA files, and 
bold face for the names of the controls in the interface. 

2. Brief description of the MESA output 

MESA is a one-dimensional stellar evolution code. The output data is 
parameterized by the value of the star age and the radial distance from the 
star center. Most of the output data is organized in a large number of profiles 
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("logn.data" files, with n an integer). The main section of each profile is a 
table with data referring to a particular age and each row referring to a 
particular zone in the star. Different zones correspond to different distances 
from the center. 

Besides the profiles, MESA also produces a "star. log" file which includes 
global information about the star at different times, and a "profiles. index" 
which provides a useful connection between the profiles and "star. log". All 
these files are created during a MESA run and, by default, are contained in 
the LOG folder of the star/work directory. Below is a brief description of the 
MESA output files. For more information, cfr. the MESA literature [TJ [2]. 

The MESA output folder contains 1 file "star. log", a large number of 
profiles, 1 file, " profiles. index" . 

• The file "star. log" includes global information about the star at differ- 
ent times. The second and third row of this file include the names (row 
2) and values (row 3) of some physical quantities characterizing the 
star, for example its initial mass and metallicity. This information is 
accessible from the interface by selecting the GENERAL radio button 



in the GENERAL INFO panel of the interface (see section 5.2). 

The sixth row contains the names of some age-dependent physical quan- 
tities, such as effective temperature or central density, and all the rows 
below that show the values of these quantities at different ages. Each 
row is indexed by a different model-number and represents a different 
age of the star. 

The profiles ("logn.data" files) contain detailed information about the 
structure of the star, each file referring to a specific age. Here, n is the 
log file number, also referred to as the log or profile number. 

The second and third row of these files include the names (row 2) and 
values (row 3) of some physical quantities characterizing the particular 
profile, for example the age of the star. This information is accessible 
from the interface by selecting the DETAILED radio button in the 



GENERAL INFO panel of the interface (see section |5_2j). 

The sixth row contains the names of some position-dependent physical 
quantities, such as temperature or density, and all the rows below that 
show the values of these quantities in the different zones. 
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• The file "profiles. index" is an index of the "logn.data" files. It has 
three columns. The most interesting (for our purpose) are the first and 
the third. The first contains the model-number, which indicates a spe- 
cific row of the file "star. log" (each row has a different model .number) . 
The third column has the log file number. In this way "profiles. index" 
provides a link among the various "logn.data" and "star. log". 

The number of different profiles and the amount and kind of information in 
each file depend on the particular run. 

3. General structure of the MESAFace code 

The MESAFace code contains two scripts, labeled as (* SCRIPT 1 *) 
and (* SCRIPT 2 *), which should be run consecutively. 

The first script extracts all the data from a MESA run and organizes 
them into tables easily accessible by the interface (see section [4]). Although 
extracting all the MESA output at once may be slow, after that, the interface 
can access all the data very quickly, allowing a dynamical manipulation and 
visualization of the information. 

The interface is created by the second script, labeled (* SCRIPT 2 *) in 
the code and described in section 13.21 and [5] 

The choice to have two scripts is a practical one: The second script, which 
normally runs in no more than a second or so, allows several customizations 
of the interface, for example it allows the user to set the style of the graphs. 
Having this script separated from the first one allows the user to change some 
features in the interface or in the plot style without having to download the 
data each time. 

3.1. Structure of the first script 

The first script can be divided in two sections: 

1. The first section, which ends before the definition of the function age, 
sets the path to the folder with the MESA output data and downloads 
the data. 

2. The second section organizes the data (see section [1]). 

The variable slash allows Mathematica to read the location of the output 
files with different operating systems. If the output data are on the web, the 
variable slash has to be set equal to "/". 
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3.2. Structure of the second script 

The second script can be divided into three main sections: 

1. The section contained within the comment lines (* General Settings *) 
and (* DON'T CHANGE *) at the beginning of the second script allows 
the user to customize the interface. In this section, it is possible to 
define the style of the graphs, the labels, and the buttons to show in 
the interface. 

2. The section below the comment line (* Plot and Info Section*) 
produces the information to be presented in the three vertical panels 



on the right hand side of the interface (see section 5.2). 

The section after the comment line (* Image Size *) creates and 

manages the controls to be shown on the left hand side of the interface 



(see section 5.1 ) 



3.3. Local and global variables 

Most of the variables used in the scripts are local (they are visible only 
within the script). A variable is made local by including it in the curly 
brackets at the beginning of the Module command. 

However, some variables defined in the first script need to be accessed by 
the second script and, therefore, they cannot be defined locally. These global 
variables are: 

• path: it defines the path to the folder with the MESA output data. 

• star: it is a table and contains the content of the file "star. log". 

• log [logNumber] : it is an array of tables with the content of the profiles. 
logNumber is an index equal to the log file number (see section [2]). The 
table log[n] corresponds to the file "logn.data". 

• profiles: it is a table and contains the content of the file "pro- 
files. index" . 

• logAge: it is a two column table with, respectively, the log file number 
and the star age of each profile. 

• maxModelLength: it is an integer equal to the number of lines of the 
profile which has the largest number of lines. 
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If it is necessary to debug or to use a result outside a MESAFace session, 
a local variable can be made global by taking it out of the list in the curly 
brackets at the beginning of the Module command. 

In general, however, it is not recommended to use nonlocal variables out- 
side MESAFace during a session. 

4. Loading and organizing of the files 

The goal of MESAFace is to provide a way to access the data dynamically. 
In order to do that, MESAFace downloads all the data at once, either from 
the hard-drive or from the web, and saves it in particular variables. This may 
be a rather slow process, especially if the data are to be extracted directly 
from a web location. After the data is downloaded, however, the access to 
the information is very fast. 

The progress in downloading is indicated: a numerical value represents 
the actual number of downloaded profiles while a progress-bar shows the 
relative progress. 

4-1. Extraction of the MESA output 

The job of the first script of MESAFace is just to download and organize 
the MESA output data. Mathematica looks in the folder defined by the 
variable path for all the files with names "star. log", "profiles. index" and 
"logn.data" (it is essential that the output files have those names, as it is for 
a default run). The variable path can point to a folder on the hard drive or 
on the web. 

The files "star. log" and "profiles. index" are saved (as tables) respectively 
in the variable star and profiles. Analogously, the "logn.data" files are 
saved in the array of tables log[indx] , where indx is the log number n. For 
example, the file "log33.data" is saved as log [33]. 

4-2. Extraction of the age of the star and selection of the profile to show 
One of the main features of MESAFace is to allow an easy selection of the 

profile corresponding to a certain age. To do that, the first script organizes 

the profiles in order of age in the table logAge, with the log number in column 

1 and the star age in column 2. 
The function age: 

age [i_] := log [i] [[1 + Position [log [i] , "star.age"] [ [1 , 1]], 
Position[log[i] , "star.age"] [ [1 , 2]]]]; 
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has the task of extracting the age of each profile. 

A slide-bar (more precisely, a manipulator) type control: 



{{starAge, logAge[[l, 2]], Style ["Star Age" , 12, {Bold, Blue}]}, 
logAge [ [All , 2] ] , ControlType -> Manipulator} , 

allows the user to set the value of the real variable starAge to any of the 
lines in the second column of the table logAge (which, as explained, contains 
the ages of all the profiles). 

Each time starAge is selected, Mathematica uses the table logAge to 
find the corresponding log file number, and saves it in the variable model: 

model = logAge [[Position [logAge [[All, 2]], starAge] [[1, 1]], 1]]; 

In addition, if the check-box Show Age in History Plot is checked, MESAFace 
finds which line of the file "star. log" corresponds to the age selected: 

modelNumber = prof iles [ [Position [Drop [prof iles , 1][[A11, 3]], 
model] [[1, 1]] + 1, 1]] ; 

indexAge = Position [Drop [star , 6] [[All, 1]], modelNumber] 
[[1, 1]]; 

Here, modelNumber is equal to the model number discussed above (see section 
[2|. Its value is reported in the first column of "profile. index" and in the first 
column of "star. log". 

The variable indexAge, instead, is equal to the the row number ofstar.log" 
(after its first 6 lines are dropped) corresponding to the model number (and 
therefore the age of the star). This value is used to identify the position of 
the age of the current profile in the history plots, providing a link between 
the History Plots and Profile Plots panels. 

5. The interface 

Running the second script produces a graphical interface in which the 
controls, located on the right hand side, allow the user to choose what kind 
of information to show in the visualization panels to the right. 
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5.1. Description of the controls 

The controls are coded in the section of the second script which fol- 
lows the comment line (* Beginning of the proper dynamical part *). 
They are described by variables and are normally nested in double curly 
brackets. For example, the line: 

{{variable name, Default value, "label"}, list of possible values, 
ControlType -> PopupMenu} , 

describes a variable whose value can be set by a popup-menu [5]. 

The first controls in each of the three sections of the interface are radio 
button-type controls which allow the user to choose the kind of plot (top 
two panels) or information (bottom panel) to show. They are coded in the 
section of the script below the comment line (* Beginning of the proper 
dynamical part *), at the beginning of the (* History Plot Section *), 
the (* Profile Plot Section *), and the (* Info Section *): 

{{plotType, "Customized", Style ["Type of Plot", 12, Bold]}, 
{"Customized", "HR", "CentralAbundances" , "Burnings"}, 
ControlType -> RadioButtonBar} , 

{{prof ileType, "Custom", Style ["Type of Plot", 12, Bold]}, 
{"Custom", "Abundances", "Reactions"}, 
ControlType -> RadioButtonBar}, 

{{Info, "PATH", ""},{ M PATH", "GENERAL", "DETAILED"}, 
ControlType -> RadioButtonBar}, 

These controls allow the user to set the string value of plotType, prof ileType, 
and Info. 

When these variables are set at their default values, the quantities to 
be plotted are represented by the string-valued variables xH and yH, for the 
x— and y— coordinates of the history plots and xP and yP, for the x— and 
y— coordinates of the profile plots. 

The possible values of xH and yH are the elements in the 6 th row of the 
file "star. log". The possible values of xP and yP are the elements in the 6 th 
row of any of the files "logn.data". All these options are accessible to the 
user through popup menus and buttons. The lists of buttons to show in the 
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interface are coded in the (*Buttons to show*) section of the code: 



(*Buttons to show*) 

HistoryButtonsX = {"star_age" , "log_Teff", "logJL", "logJl" , 
"log_center_T" , "log_center_Rho"} ; 

HistoryButtonsY = {"log_Teff " , "log_L", "log_R", "log_center_T" , 
" log_center_Rho " } ; 

HistoryButtonsY2 = {"log_center_P" , "center Jil", "center Jie4" , 
"center_cl2"}; 

Prof ileButtonsX = {"mass", "radius", "logR"}; 

Prof ileButtonsY = {"radius", "mass", "logR", "logT", "logRho", 

"logP", "hi", "he3", "he4"}; 
Prof ileButtonsY2 = {"cl2", "nl4", "0I6", "log_opacity" , 
"luminosity" , "non_nuc_neu"}; 

The first element of each list gives the default value of the corresponding 
variable. 

The plot functions Customized and Custom, plot the values in the two 
columns defined by xH and yH of the file "star. log" (after dropping the first 6 
rows) and the values in the two columns defined by xP and yP of the current 
file "logn.data" (again, after dropping the first 6 rows) respectively. 

The other plot functions show specific columns of the files "star. log" or 



"logn.data" in order to produce some standard plots (see section 5.2). 

Regardless of the value of the plotType and prof ileType variables, the 
following parameters define some characteristics of the graphs: 

• Cx, Cy, Dx, Dy represent the scale factors for, respectively, the x— and 
y— axis of the history plots and the x— and y— axis of the profile plots. 
Selecting n in one of the axis scale menu rescales the axis by a factor 
of 10~ n . For example, if the represents the age in years, selecting 
Cx=6 changes the units to Myr. 

• The string-valued variables f uncXH, f uncYH, f uncXP, and f uncYP define 
the operation to be performed on the data represented by, respectively, 
xH, yH, xP and yP. Their possible value is selected by popup menu type 
controls. The expression corresponding to the string is specified in the 
list DataOper at ions, in the section (* Operations on the data*). 
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• The real- valued variables of f setXH, of f setYH, of f setXP, and of f setYP 

define new zeros for the axes. 

• startH and endH define the plot range for the history plots, that is, 
the rows of the file "star. log" to be shown. Changing their value allows 
to zoom in a particular region of the history plot. 

• startP and endP define the plot range for the profile plots, that is, the 
rows of the current profile to be shown. Changing their value allows to 
zoom in a particular region of the profile plot. 

All the possible values for these variables can be set from the control section, 
on the left hand side of the interface. 

The (* Profile Plot Section*) contains two more variables: starAge 
and goToAge. 

• starAge can be equal to the age of any of the profiles from the current 
simulation. Its value can be changed dynamically through a slide-bar 
and its current value is indicated on top of the profile plot. Chang- 
ing starAge corresponds to selecting a new "logn.data" file. The log 
number corresponding to the current age is also shown on top of the 
profile plot. When the star age is changed, all the plots and the other 
information shown are dynamically updated. 

• goToAge is a logical variable, by default equal to false. If its value is 
set to true (by checking the box "Show Age in History Plot" in the 
profile section of the interface), the age selected will be shown in the 
history plot through a line or a dot (or both, depending on the kind 
of plot). The style of the line and of the dot is set by the param- 
eters AgeLineColor, AgeDotSize and AgeDotColor in the OGraphs 
colors *) section of the script: 

AgeLineColor ={Red, Dashed}; 
AgeDotSize = 0.01; 
AgeDotColor = Red; 

5.2. Visualization of the data 

When the second script is executed, Mathematica reads the value of the 
three string-valued variables plotType, prof ileType, and Info. 
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Figure 1: The plots refer to a 1 M star, with solar metallicty [6]. The top ones are 
examples of history plots. The bottom ones of profile plots. The red dot and the dashed 
line indicate the age corresponding to the profiles shown, in this case about f 2.5 Gyr. 

Then, in the following section of the code: 

Grid[{ (* History Plot *) 

{Dynamic [ToExpression [plotType] ] }, 

(* Profile Plot *) 

{Dynamic [ToExpression [prof ileType] ] }, 

(* Information *) 

{Dynamic [ToExpression [Info] ] }} , 

Alignment — > Left, Frame — > All] , 

these three strings are transformed into expressions which are evaluated in 
the section of the code labeled (* Plot and Info Section*), described 
below. In addition, the Grid function creates three panels which show the 
value of these three expressions. Examples of graphs shown in the history 
and profile panels are given in Fig|TJ 

The section (* Plot and Info Section*) , is divided into three subsec- 
tions, each responsible for one of the three graphical panels: 
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1. (* History Plots Section *) for the top panel. Defines the possible 
values for the variable plotType; 

2. (* Profile Plots Section *) for the middle panel. Defines the pos- 
sible values for the variable prof ileType; 

3. (* Info Section *) for the bottom panel. Defines the possible values 
for the variable Info; 

Below is the list of the possible values of plotType, with the results that 
they produce: 

• Customized is the default choice. In this case, the variables in the 
x— and y— axes of the graphs (in the top panel) are selected from the 
buttons or from the popup menus. Each popup menu contains the 
names of all the variables that are possible to plot (i.e., the names of 
all the columns in the "star. log" file). 

• HR produces the HR diagram, with the logarithm of the effective tem- 
perature on the x— axis and the logarithm of the luminosity on the 
y— axis. The temperature increases toward the left of the x— axis, in 
line with the standard convention for the HR diagram. 

• CentralAbundances shows the central abundance of the elements de- 
fined in the list CentralAbundancesToShow in the (* General Settings 

*) section of the code. 

• Burnings shows the energy released in the nuclear reactions defined 
in the list CentralAbundancesToShow in the (* General Settings 

*) section of the code. 

The possible values of prof ileType are 

• Custom is the default choice and works in the same way as for the 
history plots. 

• Abundances shows the profile of the abundance of the elements de- 
fined in the list Prof ileAbundancesToShow in the (* General Settings 

*) section of the code. 

• Reactions shows the energy released in the nuclear reactions defined 
in the list Prof ileBurningsToShow in the (* General Settings *) 

section of the code. 



14 



All the lists for the abundances and the reactions can be customized according 
to the user's needs. 

Finally, the possible values of Info are 

• PATH is the default value. In this case MESAFace shows the value 
of the variable path and so indicates the working folder or the web 
location from where Mathematica is extracting the data. 

• GENERAL shows general information about the star not related to 
the current profile. The information is taken from the second and third 
rows of the file "star. log". 

• DETAILED shows detailed information about the current profile. 
The information is taken from the second and third rows of the current 
profile. 

It is possible to add other kinds of plots or information by adding new op- 
tions for the variables plotType, prof ileType, and Info in the section below 
the comment line (* Beginning of the proper dynamical part *) and 
then define their expression-values in the (* Plot and Info Section*) of 
the code. 

6. Conclusions 

MESAFace is a user-friendly and efficient interface to analyze the MESA 
output data. It is written in Mathematica, a very powerful and very well- 
documented mathematical software, and it is easily customizable. 

The main purpose of this interface is to provide a tool to quickly analyze 
all the output data from a MESA run through graphs and tables. Our final 
objective was to have a very intuitive and easy-to-use instrument, accessible 
to researchers as well as to students. MESAFace allows the user to choose 
what to plot through various menus and to scroll the various profiles, or- 
ganized by age, with a slidebar. The user can also easily zoom in different 
regions of the plot, change units, set a different zero for each axis, or plot 
the log (among other functions) of the data. 

The production of high-quality graphs was not our priority, as other tools 
are available [7]. However, improving the quality and create new options 
to manipulate the aspect of a graph, is a prominent direction for future 
improvement of MESAFace. 



15 



This paper is not meant to be a proper user manual. Basic instructions 
on how to use MESAFace are accessible on-line [3]. Here, instead, we have 
described in detail the structure of the code and the meaning of the variables 
and controls. This allows the user not just to use, but if necessary, to modify 
and possibly improve this code. 
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To download MESA and for instructions on its use, visit 
|http://mesa. sour cef orge .net/| 



See http://mesastar.org/, Interesting MESA programming tools can be 
found following the link Tools & Utilities. 



See http:/ /www. mgiannotti.com/mesaface.php 



Many more details on the controls can be found in the Mathematica 
help for Manipulate. 

The inlist file to generate the data is available in the MESA test suite 
folder of MESA. The resulting data folder can also be downloaded di- 
rectly from [3]. 

An excellent choice is Tioga, available at 



|http://helix.phys.uvic.ca:8080/MESA/tools-utilities 
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